import Warning from 'components/Markdown/Warning'

export const meta = {
  title: "Using the Prisma GraphQL API",
  position: 80,
}

## Overview

Prisma APIs are consumed via HTTP. This means you can use any HTTP tool/library you like to talk to a Prisma API.

Here is the structure of an HTTP POST request that carries a `createUser` mutation:

**Header**

- `Authorization`: Carries the _service token_ (prefixed with `Bearer`) used to authenticate a request; only required if the service is deployed with a _service secret_.
- `Content-Type`: Specifies the format of the request's body (JSON), usually `application/json`.

**Body** (JSON)

- `query`: The GraphQL operation to be sent to the API; beware that despite the field being called `query` it's also used for mutations!
- `variables`: A JSON object containing the variables defined in the GraphQL operation submitted in `query`.

All examples on this page are based on a Prisma service with the following service configuration:

**prisma.yml**

```yml
datamodel: datamodel.prisma
secret: my-secret-42
```

**`datamodel.prisma`**

```graphql
type User {
  id: ID! @unique
  name: String!
}
```

## curl

[curl](https://curl.haxx.se/) is a command-line tools that (among other things) lets you send HTTP requests to URLs.

Here is how you send a `createUser` mutation to the Prisma API using curl:

```bash
curl '__YOUR_PRISMA_ENDPOINT__' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer __YOUR_SERVICE_TOKEN__' \\
--data-binary '{"query":"mutation ($name: String!) { createUser(data: { name: $name }) { id } }","variables":{"name":"Sarah"}}'
```

To **try out this example**, replace the `__YOUR_PRISMA_ENDPOINT__` and `__YOUR_SERVICE_TOKEN__` placeholders with corresponding values from your Prisma service and paste the resulting snippet into your terminal.

This results in the following mutation getting resolved by the Prisma API:

```graphql
mutation {
  createUser(data: {
    name: "Sarah"
  }) {
    id
  }
}
```

**Try out this example**:

1. Replace the `__YOUR_PRISMA_ENDPOINT__` and `__YOUR_SERVICE_TOKEN__` placeholders with corresponding values from your Prisma service
1. Paste the resulting snippet into your terminal and hit enter

## fetch (Node.JS)

The [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) function lets you to send HTTP requests to URLs from JavaScript.

Here is how you send a `createUser` mutation to the Prisma API using `fetch` in a Node script:

```js
const fetch = require('node-fetch')

const endpoint = '__YOUR_PRISMA_ENDPOINT__'

const query = `
mutation($name: String!) {
  createUser(data: {
    name: $name
  }) {
    id
  }
}
`

const variables = { name: 'Sarah' }

fetch(endpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization:
      'Bearer __YOUR_SERVICE_TOKEN__',
  },
  body: JSON.stringify({ query: query, variables: variables }),
})
  .then(response => response.json())
  .then(data => console.log(JSON.stringify(data)))
```

This results in the following mutation getting resolved by the Prisma API:

```graphql
mutation {
  createUser(data: {
    name: "Sarah"
  }) {
    id
  }
}
```

**Try out this example**:

1. Replace the `__YOUR_PRISMA_ENDPOINT__` and `__YOUR_SERVICE_TOKEN__` placeholders with corresponding values from your Prisma service
1. Store the resulting snippet in a JavaScript file called `script.js`
1. Install the `node-fetch` library by running `yarn add node-fetch` in the same directory where `script.js` is located
1. Execute the script using the following terminal command: `node script.js`

## graphql-request

The [`graphql-request`](https://github.com/prismagraphql/graphql-request) library is a lightweight wrapper on top of `fetch` which you can use to save writing boilerplate code. It is mostly used in scripts and smaller applications that need to talk to a GraphQL API.

### Using `request`

<Warning>

`request` does not support passing _headers_ to the request ([yet](https://github.com/prismagraphql/graphql-request/pull/33)). Therefore, this particular example assumes your Prisma service was deployed without a service secret.

</Warning>


```js
const { request } = require('graphql-request')

const query = `
mutation($name: String!) {
  createUser(data: {
    name: $name
  }) {
    id
  }
}
`

const variables = { name: 'Sarah' }

request('__YOUR_PRISMA_ENDPOINT__', query,  variables)
  .then(data => console.log(data))
```

**Try out this example**:

1. Replace the `__YOUR_PRISMA_ENDPOINT__` and `__YOUR_SERVICE_TOKEN__` placeholders with corresponding values from your Prisma service
1. Store the resulting snippet in a JavaScript file called `script.js`
1. Install the `graphql-request` library by running `yarn add graphql-request` in the same directory where `script.js` is located
1. Execute the script using the following terminal command: `node script.js`

### Using `GraphQLClient`

```js
const { GraphQLClient } = require('graphql-request')

const client = new GraphQLClient('__YOUR_PRISMA_ENDPOINT__', {
  headers: {
    Authorization: 'Bearer __YOUR_SERVICE_TOKEN__',
  },
})

const query = `
mutation($name: String!) {
  createUser(data: {
    name: $name
  }) {
    id
  }
}
`

const variables = { name: 'Sarah' }

client.request(query, variables)
  .then(data => console.log(data))
```

**Try out this example**:

1. Replace the `__YOUR_PRISMA_ENDPOINT__` and `__YOUR_SERVICE_TOKEN__` placeholders with corresponding values from your Prisma service
1. Store the resulting snippet in a JavaScript file called `script.js`
1. Install the `graphql-request` library by running `yarn add graphql-request` in the same directory where `script.js` is located
1. Execute the script using the following terminal command: `node script.js`

## GraphQL Playground

A GraphQL Playground is a GraphQL IDE that lets you send queries, mutations and subscriptions to GraphQL APIs.

You can open a Playground for your Prisma API by navigating your terminal into the same directory where your service's prisma.yml is located and run the following command:

```bash
prisma playground
```

If your prisma.yml contains a `secret`, the opening Playground will already be configured with a _service token_. You can verify this in the **HTTP HEADERS** pane in the bottom-left corner:

![](https://i.imgur.com/4Yvj4tD.png)

This means you can start sending requests to the Prisma API right away. Queries, mutations and subscriptions are written in the left pane of the Playground. You then hit the **Play**-button to actually send the request. The results will appear in the right pane of the Playground:

![](https://i.imgur.com/lNXNKXR.png)


## Apollo Client

[Apollo Client](https://www.apollographql.com/client) is a sophisticated GraphQL client library commonly used in larger frontend applications. While all previous examples used a generic utility to send queries and mutations alike, Apollo Client exposes dedicated methods for sending queries and mutations: `query` & `mutate`

### query

```js
const { ApolloClient } = require('apollo-boost')
const gql = require('graphql-tag')

const endpoint = 'https://eu1.prisma.sh/nikolas-burk/demodofin/dev'

const client = new ApolloClient({
  uri: endpoint
});

const query = gql`
  query {
    users {
      id
      name
    }
  }
`

client.query({
  query: query,
})
  .then(data => console.log(data))
```

### mutate

```js
const { ApolloClient } = require('apollo-boost')
const gql = require('graphql-tag')

const endpoint = 'https://eu1.prisma.sh/nikolas-burk/demodofin/dev'

const client = new ApolloClient({
  uri: endpoint
});

const mutation = gql`
  mutation($name: String!) {
    createUser(data: {
      name: $name
    }) {
      id
    }
  }
  `

const variables = { name: 'Sarah' }

client.mutate({
  mutation: mutation,
  variables: variables
})
  .then(data => console.log(data))
```